//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IPersistentFactory.cs
//
//  Description: Interface for persistent factories.
// 
//--------------------------------------------------------------------------

using System;
using System.Collections.Generic;
using System.Text;

namespace Chili.Opf3
{
	/// <summary>
	/// Interface implemented by classes that create persistent object instances.
	/// </summary>
	/// <remarks>
	/// <para>
	/// This interface is implemented by classes that create persistent object instances from 
	/// persistent object types. The interface is registered with the static
	/// <see cref="ObjectContext">ObjectContext.PersistentFactory</see> method and queried 
	/// on each creation of a persistent object instance.
	/// </para>
	/// <para>
	/// The interface should be implemented to improve the performance of persistent object
	/// creation.
	/// </para>
	/// <example>
	/// The following example shows how to implement and register the interface.
	///		<code lang="CS">
	/// public sealed class MyPersistentFactory : IPersistentFactory
	/// {
	///		public object CreateInstance(Type type, object[] parameters)
	///		{
	///			if (type == typeof(User))
	///				return new User();
	///			else if (type == typeof(Call))
	///				return new Call();
	///
	///			// For all other types return null.
	///			return null;
	///		}
	/// }
	/// 
	/// // Other code...
	/// 
	/// // Register the factory with the ObjectContext.
	/// ObjectContext.PersistentFactory = new MyPersistentFactory();
	///		</code>
	/// </example>
	/// </remarks>
	public interface IPersistentFactory
	{
		/// <summary>
		/// Creates an instance of a persistent object type. If the factory does not support 
		/// creation of the given type, it should return null.
		/// </summary>
		/// <param name="type">The type of the persistent to create an instance for.</param>
		/// <param name="parameters">The constructor parameters for the persistent object instance.</param>
		/// <returns>An instance if the factory can create one. Null if the factory can't create an instance for the given type.</returns>
		object CreateInstance(Type type, object[] parameters);
	}
}
